/*
 * Copyright (C) 2011 JiangHongTiao
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package sk.lieskove.jianghongtiao.multithreaddownloader.request;

import sk.lieskove.jianghongtiao.multithreaddownloader.document.RemoteDocument;
import sk.lieskove.jianghongtiao.multithreaddownloader.request.exceptions.NotEnoughParametersException;
import sk.lieskove.jianghongtiao.multithreaddownloader.request.exceptions.ParameterNotAllowedException;
import sk.lieskove.jianghongtiao.multithreaddownloader.request.params.Param;

import java.util.Map;


/**
 * Common interface for web search service. User pass params for request URL
 * and then get answer. Developer have to specify which parameter is required
 * and which one is optional. 
 * 
 * Date of create: May 19, 2011
 *
 * @author JiangHongTiao <jjurco.sk_gmail.com>
 * @version 2011.0519
 */
public interface PageRequest {
    
    /**
     * get answer from web server. Answer is dependent on service implementation 
     * and parameters set. 
     * @return response is saved in XML file
     */
    public RemoteDocument getAnswer() throws NotEnoughParametersException;
    
    /**
     * @param paramName name of the parameter to insert
     * @param paramValue value for the parameter
     * @throws ParameterNotAllowedException if this parameter is not supported by this service
     */
    public void putParam(String paramName, String paramValue) throws ParameterNotAllowedException;
    
    /**
     * remove parameter and associated value
     * @param name name of the parameter to remove
     * @return value of parameter if the parameter was inserted, otherwise <code>null</code>
     */
    public String removeParam(String name);
    
    /**
     * get list of parameters already stored in class
     * @return unmodifiable list of parameters
     */
    public Map<String, Param> getParams();
}
